/*  This file is Copyright 2010 Hampton Smith
 * 
 *  This file is part of Adventure! a text-adventure game engine by Hampton
 *  Smith.
 *
 *  Adventure! is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Adventure! is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Adventure!.  If not, see http://www.gnu.org/licenses/.
 */

package edu.clemson.cs.hamptos.adventure;

import java.util.Set;

/**
 * <p>An <code>AdventureLocation</code> represents space inhabitable by the
 * player.  A location can contain targets that the player can interact with.
 * In addition, locations themselves can be the target of commands.  A command
 * is routed to a location if the command has no direct or indirect object.
 * So, for example, the command <code>"sit"</code> would be routed to the
 * location to deal with.</p>
 */
public interface AdventureLocation {

    /**
     * <p>Returns a description of the location.  This will be displayed
     * whenever the player moves into this location.</p>
     *
     * @return The description of the location.
     */
    public String getDescription();

    /**
     * <p>Asks the location to try and interpret a given
     * <code>AdventureCommand</code>.  If it understand the command, it may
     * use the given <code>AdventureEngine</code> to modify the world (i.e.,
     * move the player, add and remove targets, etc.), and/or the given
     * <code>AdventureWindow</code> to print text to the terminal.  If it
     * doesn't understand the command, it must throw a
     * <code>DoNotUnderstandException</code>.</p>
     *
     * @param c The <code>AdventureCommand</code> given by the user.  Because
     *    the command has been routed to a location instead of one of the
     *    objects, it is guaranteed that calls to
     *    <code>getDirectObject()</code>, <code>getIndirectObject()</code>,
     *    <code>getDirectObjectInvocation()</code>, and
     *    <code>getIndirectObjectInvocation()</code> will return
     *    <code>null</code>.
     * @param e The <code>AdventureEngine</code> so that the location may modify
     *    the game if it needs to in order to process the command.
     * @param w The <code>AdventureWindow</code> so that the location may print
     *    text to the terminal if it needs to in order to process the command.
     *
     * @throws DoNotUnderstandException If the location does not understand the
     *    command.
     */
    public void doCommand(AdventureCommand c, AdventureEngine e,
            AdventureWindow w) throws DoNotUnderstandException;

    /**
     * <p>Returns a list of <code>AdventureTarget</code>s present at the
     * location.  This does not include any targets in the player's inventory.
     * </p>
     *
     * @return A set of <code>AdventureTarget</code>s.
     */
    public Set<AdventureTarget> getLocalTargets();

    /**
     * <p>Adds a <code>AdventureTarget</code> to the set of those present in
     * this location.</p>
     *
     * @param t The <code>AdventureTarget</code> to add.
     */
    public void addLocalTarget(AdventureTarget t);

    /**
     * <p>Removes a <code>AdventureTarget</code> from the set of those present
     * in this location.</p>
     *
     * @param t The <code>AdventureTarget</code> to remove.
     */
    public void removeLocalTarget(AdventureTarget t);

    /**
     * <p>Returns <code>true</code> if the given <code>AdventureTarget</code>
     * is present in this location.</p>
     *
     * @param t The target to check.
     *
     * @return <code>true</code> if it is present, <code>false</code> if it is
     *    not.
     */
    public boolean containsLocalTarget(AdventureTarget t);
    
    /**
     * * <p>Returns the <code>AdventureTarget</code> in this location's array if 
     * it can be referenced by this string
     * @param t
     * @return the <code>AdventureTarget</code> if found
     * @throws ItemNotFoundException if the <code>AdventureTarget</code> is 
     *    not found
     */
    public AdventureTarget containsLocalTarget(String t) throws NoSuchTargetException;
    
    public void addListener(String target);
    
    public void removeListener(String target);
    
    public void notifyListeners(AdventureEngine e, AdventureWindow w);
}
